---
title: Gitflow
description: Implementing a Gitflow-style workflow using Terrateam's destination branches and tags
---

import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import { Icon } from '@astrojs/starlight/components';
import MermaidDiagram from '../../../../components/MermaidDiagram.astro';

## What is Gitflow?

Gitflow is a popular branching model for Git that helps teams organize feature development, releases, and hotfixes. It defines clear roles for branches and a structured process for integrating changes.  

:::tip
[Learn more about Gitflow in this Atlassian guide.](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)
:::
## Gitflow Branching Model

The Gitflow branching model consists of the following main branches:

##### `main` (or `master`)
Represents the production-ready state of your infrastructure.

##### `develop`
Serves as the integration branch for feature development and acts as a staging area before merging changes into `main`.

##### `feature/*`
Used for developing new features or enhancements. Each feature branch is created from `develop` and merged back into `develop` when complete.

##### `release/*`
Used for preparing a new release. Release branches are created from `develop`, and once they are stable, they are merged into both `main` and `develop`.

##### `hotfix/*`
Used for addressing critical issues in production. Hotfix branches are created from `main`, and once the fix is complete, they are merged into both `main` and `develop`.

<MermaidDiagram chart={`
gitGraph
   commit id: "main"
   branch dev
   commit id: "develop"
   branch feature/add-new-resource
   commit id: "feature"
   checkout dev
   merge feature/add-new-resource
   branch release/1.0
   commit id: "release"
   checkout main
   merge release/1.0
   branch hotfix/fix-critical-bug
   commit id: "hotfix"
   checkout main
   merge hotfix/fix-critical-bug
   checkout dev
   merge hotfix/fix-critical-bug
`} />

## Configuring Terrateam for Gitflow

To implement a Gitflow-style workflow with Terrateam, you’ll use the `tags`, `destination_branches`, and `workflows` sections in your `.terrateam/config.yml`.  
Below, each section is explained in detail:

### 1. Tags

Define tags to identify destination branches using regular expressions:

```yaml
tags:
  dest_branch:
    main: '^main$'
    staging: '^staging$'
    dev: '^dev$'
```
**What it does:**
- This creates a `dest_branch` tag that matches your main, staging, and dev branches.

### 2. Destination Branches

Specify which source branches are allowed to open pull requests into each destination branch:

```yaml
destination_branches:
  - branch: main
    source_branches: ['staging']
  - branch: staging
    source_branches: ['dev']
  - branch: dev
    source_branches: ['*', '!main', '!staging']
```
**What it does:**
- Only `staging` can merge into `main`.
- Only `dev` can merge into `staging`.
- Any branch except `main` or `staging` can merge into `dev` (e.g., features).

### 3. Workflows

Define different workflows for each destination branch:

```yaml
workflows:
  - tag_query: 'dest_branch:main'
    plan:
      - type: env
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: apply
  - tag_query: 'dest_branch:staging'
    plan:
      - type: env
        method: source
        cmd: ['echo', 'staging']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ['echo', 'staging']
      - type: init
      - type: apply
  - tag_query: 'dest_branch:dev'
    plan:
      - type: env
        method: source
        cmd: ['echo', 'dev']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ['echo', 'dev']
      - type: init
      - type: apply
```
**What it does:**
- Runs different Terraform workflows depending on the destination branch.
- Sets an environment variable for each environment, then runs `init`, `plan`, and `apply` as appropriate.

<details>
<summary>Full Example: Complete .terrateam/config.yml for Gitflow</summary>

```yaml
tags:
  dest_branch:
    main: '^main$'
    staging: '^staging$'
    dev: '^dev$'
destination_branches:
  - branch: main
    source_branches: ['staging']
  - branch: staging
    source_branches: ['dev']
  - branch: dev
    source_branches: ['*', '!main', '!staging']
workflows:
  - tag_query: 'dest_branch:main'
    plan:
      - type: env
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: apply
  - tag_query: 'dest_branch:staging'
    plan:
      - type: env
        method: source
        cmd: ['echo', 'staging']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ['echo', 'staging']
      - type: init
      - type: apply
  - tag_query: 'dest_branch:dev'
    plan:
      - type: env
        method: source
        cmd: ['echo', 'dev']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        cmd: ['echo', 'dev']
      - type: init
      - type: apply
```
</details>

## Workflow Example

Let's walk through an example of how the Gitflow workflow can be implemented with Terrateam using the above configuration:

<Tabs>
  <TabItem label="Feature">
    1. Create a new feature branch from `dev`: `feature/add-new-resource`  
    2. Make the necessary changes to your Terraform code in the feature branch  
    3. Open a pull request from `feature/add-new-resource` to `dev`  
    4. Terrateam will run plans on the pull request, allowing you to review the proposed changes in the `dev` environment  
    5. After the pull request is approved and merged, the changes will be incorporated into `dev`
  </TabItem>
  <TabItem label="Staging">
    1. When you're ready to deploy the changes to staging, create a pull request from `dev` to `staging`  
    2. Terrateam will run plans and applies on the staging environment, ensuring that the infrastructure is properly provisioned  
    3. If any issues are found during the staging deployment, fix them directly in the `dev` branch and repeat the process  
    4. Once the changes are stable in staging, merge the pull request into `staging`
  </TabItem>
  <TabItem label="Production">
    1. When you're ready to release the changes to production, create a pull request from `staging` to `main`  
    2. Terrateam will run plans and applies on the production environment, ensuring that the changes are properly deployed  
    3. If any issues are found during the production release, fix them directly in the `staging` branch and repeat the process  
    4. Once the changes are stable in production, merge the pull request into `main`
  </TabItem>
  <TabItem label="Hotfix">
    1. If a critical issue is discovered in production, create a new hotfix branch from `main`: `hotfix/fix-critical-bug`  
    2. Make the necessary fixes in the hotfix branch  
    3. Open a pull request from `hotfix/fix-critical-bug` to `main`  
    4. Terrateam will run plans and applies on the production environment, ensuring that the fix is properly implemented  
    5. After the pull request is approved and merged, the hotfix will be deployed to production  
    6. Merge the hotfix branch back into `dev` to ensure that the fix is included in future releases
  </TabItem>
</Tabs>

## Best Practices

When implementing a Gitflow workflow with Terrateam, consider the following best practices:
- Ensure that your destination branches and tags configuration accurately reflects your desired branching model and workflow.
- Use descriptive and meaningful names for your branches, following the Gitflow naming conventions.
- Regularly update your `dev` branch with the latest changes from `main` to keep it in sync.
